docs: streamline maintainer and contributor guides - #94
Conversation
Replace the duplicated make-target listings in the maintainers guide and AGENTS.md with a pointer to `make help`, so the docs can't drift from the Makefile. Drop decorative emoji from section headings (which also repairs the broken `#-updating-changesets` style anchors), fix the CODEOWNERS description, and normalize em-dash asides to colons. Bring `.github/maintainers_guide.md`, `.github/contributing.md`, and `.github/CODE_OF_CONDUCT.md` under rumdl linting via the `[tool.rumdl]` include list, and fix the heading levels, list formatting, and anchor links they surfaced. Convert the PR template's placeholder prompts from parentheses to HTML comments so they don't leak into submitted PR bodies. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
|
WilliamBergamin
added
docs
mwbrooks
left a comment
mwbrooks
left a comment
There was a problem hiding this comment.
✅ Thanks for adding markdown linting. This is very nice! 🙇🏻
✏️ I left a comment that's non-blocking around keeping our document make commands to make it easier for humans and agents to find common commands with less effort (mental or token usage). While documenting the help command to capture new, undocumented commands.
| ### Summary | ||
|
|
||
| (Please describe the goal of this pull request and mention any related issue numbers) | ||
| <!-- Please describe the goal of this pull request and mention any related issue numbers --> |
There was a problem hiding this comment.
comment: If we use HTML comments, I don't think they'll appear to the developer when the person is writing the pull request on GitHub. I don't think this is a big deal - but we need to leave these hints for the issue templates.
| | `make clean` | Remove .venv | | ||
| | `make cursor-install` | Install this plugin into a local Cursor for development | | ||
| | `make cursor-uninstall` | Uninstall this plugin from the local Cursor install | | ||
| Run `make help` for the full list of targets and what each does. See the [maintainers guide](.github/maintainers_guide.md#local-development--testing) for local development and testing setup. |
There was a problem hiding this comment.
thought: This is fine, but I had to admit that I prefer both informing the agent to run help but also giving the explicit commands. It reduces the loops & tokens (seeing the commands immediately) and still gives flexibility for undocumented command (running help).
| make format # Auto-format: Ruff for Python, rumdl --fix for Markdown | ||
| make typecheck # Mypy static type checks | ||
| ``` | ||
| Run `make help` to see the available targets and what each one does. It reads the |
There was a problem hiding this comment.
thought: Personally, I'd rather have these explicit commands. As a maintainer, I'm often searching for something specific like "test" because I'm looking for the documented command. By just documenting help, it makes it harder for me to find what I'm looking for.
My suggestion would be to add help to the list of documented commands - in case there are undocumented commands.
| ".github/maintainers_guide.md", | ||
| ".github/contributing.md", | ||
| ".github/CODE_OF_CONDUCT.md", |
There was a problem hiding this comment.
question: Is there value is using a wildcard here instead?
| ".github/maintainers_guide.md", | |
| ".github/contributing.md", | |
| ".github/CODE_OF_CONDUCT.md", | |
| ".github/**/*.md", |
There was a problem hiding this comment.
I think using a wildcard here might mess up some of our templates 🤔
Address PR review: keep the documented make commands explicit so humans and agents find common commands without running help, while retaining the `make help` pointer for undocumented targets. Descriptions are aligned to the Makefile's own help text (e.g. `make clean` also removes the Cursor install). Also refresh the now-stale rumdl scope sentence to mention the .github/ docs added to the include list in this PR. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
2 participants
Summary
This pull request tidies up the repo's contributor- and maintainer-facing docs and brings them under markdown linting.
Preview
Testing
make lintpasses (now covering the three newly-included.github/*.mdfiles).make test-unitpasses..github/maintainers_guide.mdand.github/contributing.mdon the branch and confirm the intra-doc anchor links (e.g. "Updating Changesets", "Local Development & Testing") resolve.Notes
Requirements
make testand the tests pass.